TKpopMenu

      XFCN,MDEF
      No. 4406
      Version:  5.0 (ONLY for Registered owners of ToolKit™)
      Copyright © 1990 - 1994 by Stan Gilbert
_____________________________________________________

TKpopMenu creates popUp menus from unlimited TEXT resources, or from a HyperCard™ container, or from real MENU resources.  Supports hierarchical menus, ICONS, reduced ICONs, SICNs (small icons), special FONT, FONT Size, and resource menus.  It will also create PICTure type menus.

                         ∂
Examples

ÓÊ€get TKpopMenu("Animals")
ÊÊﬂget TKpopMenu("Animals",left of me,bottom of me)
ÊÊﬂget TKpopMenu("Animals",the mouseH, the mouseV)
ÊÊﬂget TKpopMenu("XCMDs,"&return,"","","true")

Parameters

Ó›get TKpopMenu ("myMenu")

Parameter 1

name:  name of menu resource for the appropriate type of menu (TEXT, PICT, MENU).  If this is left empty then it is assumed the item list is literal and passed in the 5th parameter.

Ó›get TKpopMenu ("myMenu", left of me + 1)

Parameter 2

LEFT:  left postition of menu.  If it is "" then the default is left of target

Ó›get TKpopMenu ("myMenu", left of me + 1, bottom of me)

Parameter 3

TOP:  top position of menu.  If it is "" then the default is bottom of target

Parameter 4

cmd:  a list of the following appropriate commands, separated by commas, and enclosed in quotes.  Not case sensitive.

For TEXT menus:
 menu:  specify use of a MENU type resource of the specified 
    ﬁ‹name in parameter 1
 sort:  sort the item list

For PICT menus:

Ó›get "pict,across3,down1,cellH75,cellW75,loc"
 ﬂ€Get TKpopMenu("pMenu",left of me - 1,bottom of me - 1,it)

 pict:  specify use of a PICT type resource of the specified 
   ﬂ›name in parameter 1
 across + number:  how many PICT menu cells across
 down + number:  how many PICT menu cells down
 cellH + number:  height of each cell
 cellW + number:  width of each cell

For ALL menus:
 loc:  use local coordinates.

Parameter 5

itemList:  This is the item list from a HyperCard™ container.  It is useful for modifying the item list before the menu is shown.  For instance, you can fetch a basic item list from a TEXT resource using TKdoTEXT, modify it by enabling/disabling items, adding check marks, etc. and then passing the list to TKpopMenu.

• Requirements
__________________________________________________

ÓÊTKpopMenu has no special requirements that would provoke the dreaded ı.  If the item list is missing you will get a "Beep" when you try to use the menu and if any ICONs or SICNs  required in the menu are missing they simply will not show up on the menu.

ÓÊTKpopMenu MUST be used in a mouseDOWN handler because menu handling is performed when the user clicks and holds the mouse button DOWN.

• Return Values
__________________________________________________

ÓÊreturns MenuNAME,ItemNAME

MenuName  FIRST ITEM - hierarchical menus only
ItemName  SECOND ITEM - ALWAYS item name selected

   Nothing selected        ""
   Non Hierarchical item   ",itemName"
   Hierarchical item       "menuName,itemName"

In BOTH cases where a selection was made a COMMA "," was in the result so that the ITEM selected is ALWAYS the second item of the result.

• Related Topics
__________________________________________________

ÓÊSee TKdoTEXT (for creating TEXT resources).  NOTHING manages popUp menus faster or more efficiently than the ToolKit™ TEXT Resource Editor.

SEE:  Menus tutorial included with ToolKit™ for a complete explanation of using popUp menus with many examples and scripting tips.

• Special Features
__________________________________________________

ÓÊThere are a couple of unique features in this XFCN.  First, you do not normally pass an item list to this XFCN.  Instead, you pass the name of a TEXT resource in the stack.

Secondly, TKpopMenu returns what you select.  That means you will not have to modify your handler for the menu items if you edit the item list.

Another unique feature is the ability to create a menu list of ANY resource type in your stack.  For instance:

ÊÊÊTEXT,

you will get a hierarchical menu item called TEXT with a sorted submenu of all the 'TEXT' resources in the stack.  That strange looking character (the box) following the comma is option/shift 'R' for Resource.

• PICT Type Menus

ÈÊTKpopMenu allows you to create PICTure type menus.  This is done by sending certain specifiers to TKpopMenu.  A PICT type menu consists of a number of cells, all of which must be equal in size.  They do NOT have to be square, that is, equal on all sides.  Rectangles are permitted, but, they all must be the same size.  The only limit to the number of cells is a practical one which is the screen size.  The steps to using these menus are as follows:

1. Create a graphic (picture) of the menu the way you want to see it.  The PICT should be composed of a number of equal sized cells, or rectangles.  Color the PICT if you want.

2. Copy the inner contents of the PICTure and store it as a PICT resource in your stack.  Remember, the menu itself will frame the picture, so, you want to copy the contents of the PICTure just inside the overall border of your PICTure.  Make sure the PICT resource has a name.

3. Now you can call TKpopMenu with the following specifiers:

PICT,ACROSSn,DOWNn,CELLWn,CELLHn   where

PICT commands TKpopMenu to create a PICT type menu
ACROSSn specifies n cells ACROSS
DOWNn specifies n cells DOWN
CELLWn specifies cells of n width (actual outside width - 1)
CELLHn specifies cells of n height (actual outside height - 1)

The commands are not case sensitive and the commas are not necessary.

ÊˆÊCLICK HERE to see an illustration of this.

 m LICK AND HOLD to see Menu1

The script might look like this:

  on mouseDown
    get "pict,across3,down1,cellw124,cellh124"
    get TKpopMenu("myPICTname","","",it)
    if it = "" then exit to hyperCard
    if it = 1 then
      -- process "No Preppies"
    else if it = 2 then
      -- process "No Smoking"
    else if it = 3 then
      -- process "No Nukes"
    end if
  end mouseDown

ÓÊWhat is returned is the number of the cell selected, from left to right and top to bottom.

ÈÊYou can use two or more menu PICTs to show some intermediate result.  The PhoneBook stack provided with ToolKit™ illustrates this.  One of the things the control menu allows you to do is insert notes for any given name.  If no notes exist the menu appears with an empty document representing the hidden note field for a name.  This is illustrated by the following example:

 m LICK AND HOLD to see Menu2

Once notes are posted to a name the menu will have a document with writing in it, like this:

 m LICK AND HOLD to see Menu3

The name of the PICT to use is simply changed as according to the contents of the field used to hold notes.  The part of the script that does this looks like this:

  •
  •
        
  get "pict,across3,down1,cellH75,cellW75"
  if bg fld "Notes" = "" then
    get TKpopMenu("Menu1","","",it)
  else
    get TKpopMenu("Menu2","","",it)
  end if
        
  •
  •

More Information

ÓÊMeta-characters are special characters inserted before items that allow the display of ICONs, SICNs, different font styles, cmd key equivalents.  Meta-characters are always followed by another character to further define the modification.

Meta-character Features

(Ê⁄Disables, or dims, an item.
/Ê⁄Cmd Key equivalent - "Quit/Q" yields "Quit‡˚Q"
!Ê€puts character following it before the item as a check
      mark.  Use "Key Caps" DA to locate checkmark (ctl R)
      to copy/paste
~ﬂ›followed by id of SICN (257 to 511)
^    followed by id of ICON (257 to 511)
>    followed by id of ICON to be reduced (257 to 511)
<    followed by character to set text style to:

         B  Bold
         I  Italic
         U  UnderLine
         O  Outline
         S  Shadow

• Beyond the Toolbox - Resource Menus
__________________________________________________

TKpopMenu goes beyond the toolbox.  Suppose we wanted a list of all ICONs and XCMDs to show up in a hierarchical menu.

ÊÊÊÊÊICONs,
ÊÊÊÊÊXCMDx,

The little box following each item is an option/shift "R" (for 'Resource').  It directs TKpopMenu to build a sorted submenu of all available resources of the specified type IN THE CURRENT STACK.

The first four characters of the menu item MUST match EXACTLY the name of a class of resources (ie. Icon is not ICON).  It is case sensitive.  Resource types are always four characters long.  TKpopMenu does not care what follows the first four characters (notice the small "s" after ICON).  The option/shift 'R' tells TKpopMenu to compile a SORTED list of all the resources of type ICON into a hierarchical submenu.

See Inside Macintosh™ volume 1 page 107 for information on resource types.

• Fonts

Fonts are a special case:

ÊÊÊÊÊFONTs,

The little box here is an option/shift "F" because we want TKpopMenu to build a menu of ALL available FONTs including the System, HyperCard, Home, and the current stack.  Option/shift "R" would only show fonts in the current stack.

Another unique TKpopMenu feature is FONT sizes.

ÊÊÊÊÊSize,

The "special character" in this case is an option/shift "S".  This will create a size menu for fonts and outline the sizes available for the currently selected font.

See TKresFile for resources in another stack.

∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞∞